/**
 * Software License, Version 1.0
 * 
 * Copyright 2008 The Trustees of Indiana University.  All rights reserved.
 * 
 *
 *Redistribution and use in source and binary forms, with or without 
 *modification, are permitted provided that the following conditions are met:
 *
 *1) All redistributions of source code must retain the above copyright notice,
 * the list of authors in the original source code, this list of conditions and
 * the disclaimer listed in this license;
 *2) All redistributions in binary form must reproduce the above copyright 
 * notice, this list of conditions and the disclaimer listed in this license in
 * the documentation and/or other materials provided with the distribution;
 *3) Any documentation included with all redistributions must include the 
 * following acknowledgment:
 *
 *"This product includes software developed by the Community Grids Lab. For 
 * further information contact the Community Grids Lab at 
 * http://communitygrids.iu.edu/."
 *
 * Alternatively, this acknowledgment may appear in the software itself, and 
 * wherever such third-party acknowledgments normally appear.
 * 
 *4) The name Indiana University or Community Grids Lab or Granules, 
 * shall not be used to endorse or promote products derived from this software 
 * without prior written permission from Indiana University.  For written 
 * permission, please contact the Advanced Research and Technology Institute 
 * ("ARTI") at 351 West 10th Street, Indianapolis, Indiana 46202.
 *5) Products derived from this software may not be called Granules, 
 * nor may Indiana University or Community Grids Lab or Granules appear
 * in their name, without prior written permission of ARTI.
 * 
 *
 * Indiana University provides no reassurances that the source code provided 
 * does not infringe the patent or any other intellectual property rights of 
 * any other entity.  Indiana University disclaims any liability to any 
 * recipient for claims brought by any other entity based on infringement of 
 * intellectual property rights or otherwise.  
 *
 * LICENSEE UNDERSTANDS THAT SOFTWARE IS PROVIDED "AS IS" FOR WHICH NO 
 * WARRANTIES AS TO CAPABILITIES OR ACCURACY ARE MADE. INDIANA UNIVERSITY GIVES
 * NO WARRANTIES AND MAKES NO REPRESENTATION THAT SOFTWARE IS FREE OF 
 * INFRINGEMENT OF THIRD PARTY PATENT, COPYRIGHT, OR OTHER PROPRIETARY RIGHTS. 
 * INDIANA UNIVERSITY MAKES NO WARRANTIES THAT SOFTWARE IS FREE FROM "BUGS", 
 * "VIRUSES", "TROJAN HORSES", "TRAP DOORS", "WORMS", OR OTHER HARMFUL CODE.  
 * LICENSEE ASSUMES THE ENTIRE RISK AS TO THE PERFORMANCE OF SOFTWARE AND/OR 
 * ASSOCIATED MATERIALS, AND TO THE PERFORMANCE AND VALIDITY OF INFORMATION 
 * GENERATED USING SOFTWARE.
 */

package cgl.granules.dataset;

import java.io.IOException;
import java.nio.ByteBuffer;
import java.util.Enumeration;

/**
 * The interface for accessing a dataset comprising files.
 * 
 * @author Shrideep Pallickara
 * 
 */
public interface FileAccess extends Dataset {
	/**
	 * Checks to see if the file is part of a given dataset
	 * 
	 * @param fileName
	 *            The name of the file
	 * @return <code>true</code> if the file is a part of the dataset;
	 *         <code>false</code> otherwise.
	 */
	public boolean isPartOfDataset(String fileName);

	/**
	 * Returns the current size of the file in question
	 * 
	 * @param fileName
	 *            The name of the file
	 * @return The current size of the file
	 * @throws DatasetException
	 *             If there are problems retrieving the FileChannel
	 *             corresponding to the file
	 * @throws IOException
	 *             If there are IO problems in completing the operation.
	 */
	public long size(String fileName) throws DatasetException, IOException;

	/**
	 * Retrieves the position of filePointer for the given dataset
	 * 
	 * @param fileName
	 *            The name of the file.
	 * @return The position of filePointer for the given dataset
	 * @throws DatasetException
	 *             If there are problems retrieving the FileChannel
	 *             corresponding to the file
	 * @throws IOException
	 *             If there are IO problems in performing the operation
	 */
	public long getPosition(String fileName) throws DatasetException, IOException;

	/**
	 * Sets the position of filePointer for one of the file in the given
	 * dataset.
	 * 
	 * @param fileName
	 *            The file
	 * @param newPosition
	 *            The new position for the pointer
	 * @throws DatasetException
	 *             If there are problems retrieving the FileChannel
	 *             corresponding to the file
	 * @throws IOException
	 *             If there are IO problems in performing the operation
	 */
	public void setPosition(String fileName, long newPosition)
			throws DatasetException, IOException;

	/**
	 * Attempts to read a set of bytes from the underlying file.
	 * 
	 * @param filename
	 *            The file to be read
	 * @param bytesToRead
	 *            The byte[] to be read into
	 * @return The number of bytes read, possibly zero, or -1 if the channel has
	 *         reached end-of-stream
	 * @throws DatasetException
	 *             If there are problems retrieving the FileChannel
	 *             corresponding to the file
	 * @throws IOException
	 *             If there are IO problems in performing the operation
	 */
	public int read(String filename, byte[] bytesToRead)
			throws DatasetException, IOException;

	/**
	 * Attempts to read a set of bytes from the underlying file.
	 * 
	 * @param fileName
	 *            The file to be read
	 * @param readBuffer
	 *            The buffer to be read into
	 * @return The number of bytes read, possibly zero, or -1 if the channel has
	 *         reached end-of-stream
	 * @throws DatasetException
	 *             If there are problems retrieving the FileChannel
	 *             corresponding to the file
	 * @throws IOException
	 *             If there are IO problems in performing the operation
	 */
	public int read(String fileName, ByteBuffer readBuffer)
			throws DatasetException, IOException;

	/**
	 * Write the specified Buffer to the file corresponding to the specified
	 * file.
	 * 
	 * @param fileName
	 *            The file to be written to
	 * @param writeBuffer
	 *            The buffer holding the bytes to be written
	 * @return The number of bytes written, possibly zero
	 * @throws DatasetException
	 *             If there are problems retrieving the FileChannel
	 *             corresponding to the file
	 * @throws IOException
	 *             If there are IO problems in performing the operation
	 */
	public int write(String fileName, ByteBuffer writeBuffer)
			throws DatasetException, IOException;

	/**
	 * Writes a byte[] to a give file.
	 * 
	 * @param fileName
	 *            The file to be written to
	 * @param bytesToWrite
	 *            The byte[] to be written.
	 * @return The number of bytes written, possibly zero
	 * @throws DatasetException
	 *             If there are problems retrieving the FileChannel
	 *             corresponding to the file
	 * @throws IOException
	 *             If there are IO problems in performing the operation
	 */
	public int write(String fileName, byte[] bytesToWrite)
			throws DatasetException, IOException;

	/**
	 * Adds a file with the specified permission "r", "w" or "rw" to this
	 * dataset.
	 * 
	 * @param filename
	 *            The name of the file
	 * @param permissions
	 *            The permissions associated with this file
	 * @throws NullPointerException
	 *             If the specified filename is NULL
	 * @throws DatasetException
	 *             If there are problems adding this file
	 * 
	 */
	public void addFile(String filename, String permissions)
			throws DatasetException;

	/**
	 * Removes a file from this dataset.
	 * 
	 * @param filename
	 *            The name of the file
	 * @throws NullPointerException
	 *             If the specified filename is NULL
	 * @throws DatasetException
	 *             If there are problems removing this file
	 */
	public void removeFile(String filename) throws DatasetException;

	/**
	 * Retrieves the list of files in this dataset
	 * 
	 * @return An enumeration of the files in this dataset.
	 */
	public Enumeration getFilenames();

}
